home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_kdelibs.idb / usr / freeware / kde / include / ktmainwindow.h.z / ktmainwindow.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  12.5 KB  |  405 lines
  1. #ifndef _KWIDGET_H
  2. #define _KWIDGET_H
  3.  
  4. #include <stdlib.h>
  5. #include <qwidget.h>
  6. #include <qlist.h>
  7. #include <ktoolbar.h>
  8. #include <kmenubar.h>
  9. #include <kstatusbar.h>
  10. #include <kconfig.h>
  11.  
  12. /**
  13.  * Another top level widget that provides toolbars, a status line and a frame.
  14.  * It should be used as a toplevel (parent-less) widget and
  15.  * manages the geometry for all its children, including your
  16.  * main widget.
  17.  *
  18.  * Normally, you will inherit from KTMainWindow (further: KTMW).
  19.  * Then you must construct (or use some existing) widget that will be
  20.  * your main view. You set that main view only once.
  21.  *
  22.  * You can add as many toolbar(s) as you like. There can be only one Menubar
  23.  * and only one StatusBar.
  24.  *
  25.  * Toolbars, Menubar, and StatusBar are generated by the KTMW and - unlike
  26.  * KTopLevelWidget - MUST NOT BE DELETED. KTMW will handle that internaly.
  27.  *
  28.  * KTMainWindow maintaines the layout and resizing of all elements
  29.  * (toolbars, statusbar, main widget, etc).  KTW now handles fixed-size
  30.  * and Y-fixed main views properly. Just set fixed size or
  31.  * your main view. You can change it runtime, the changes will take effect
  32.  * on next updateRects call. Do not set fixed size on window! You may set
  33.  * minimum or maximum size on window, but only if main view is freely
  34.  * resizable. Minimum width can also be set if main view is Y-fixed.
  35.  *
  36.  * KTMainWindow will set icon, mini icon and caption,  which it gets
  37.  * from KApplication. It provides full session management, and will save
  38.  * its position geometry and positions of toolbar(s) and menubar on
  39.  * logout. If you want to save aditional data, overload saveProperties and
  40.  * (to read them again on next login) readProperties. To warn user
  41.  * that application has unsaved data on logout use setUnsavedData.
  42.  *
  43.  * There is also a macro RESTORE which can restore all your windows
  44.  * on next login.
  45.  *
  46.  * This class is based on (and very much the same as)
  47.  * KTopLevelWidget from Sven Radej, though easier to use. It
  48.  * is used by the kless programming example of the kdesdk,
  49.  * which is an excellent example how to use this class.
  50.  *
  51.  * KTMainWindow might be replaced/extended in the future to
  52.  * KMainWindow which will be a child of QMainWindow. Anyway,
  53.  * the current interface (as well as KTopLevelWidget) will be
  54.  * supported for compatibility reasons. It is also probable that
  55.  * both widgets will merge.
  56.  *
  57.  * @see KApplication
  58.  * @see KTopLevelWidget
  59.  * @short KDE top level main window
  60.  * @author Stephan Kulow (coolo@kde.org) Maintained by Matthias Ettrich (ettrich@kde.org) */
  61. class KTMainWindow : public QWidget {
  62.     Q_OBJECT
  63.  
  64.         friend class KToolBar;
  65.  
  66. public:
  67.     /**
  68.      * Constructor.
  69.      */
  70.     KTMainWindow( const char *name = 0L );
  71.     /**
  72.      * Destructor. Will also destroy the toolbars, and menubar.
  73.      */
  74.     ~KTMainWindow();
  75.  
  76.     /** Deletes all KTMainWindows. This is a good thing to call before
  77.       * an applications wants to exit via kapp->quit(). Rationale: The
  78.       * destructors of main windows may want to delete other widgets
  79.       * as well. Now, if an application calls kapp->quit() then Qt
  80.       * will destroy all widgets in a somewhat random order which may
  81.       * result in double-free'ed memory (=segfault). Since not every
  82.       * program checks for QApplication::closingDown() before deleting
  83.       * a widget, calling KTMainWindow::deleteAll() before is a good
  84.       * and proper solution.  
  85.      */
  86.   static void deleteAll();
  87.  
  88.     /**
  89.      * Add a toolbar to the widget.
  90.      * A toolbar added to this widget will be automatically laid out
  91.      * by it.
  92.      *
  93.      * The toolbar must have been created with this instance of
  94.      * KTMainWindow as its parent.
  95.      *
  96.      * Usually you do not need this function. Just refer to a toolbar
  97.      * with toolBar(index) instead and the KTMainWindow will 
  98.      * create it for you. Anyway addToolBar() is useful if you want
  99.      * to pass additional arguments to the toolbar's constructor.
  100.      * (Matthias) */
  101.     int addToolBar( KToolBar *toolbar, int index = -1 );
  102.  
  103.     /**
  104.      * Set the main client widget.
  105.      * This is the main widget for your application; it's geometry
  106.      * will be automatically managed by KTMainWindow to fit the
  107.      * client area, constrained by the positions of the menu, toolbars
  108.      * and status bar. It can be fixed-width.
  109.      *
  110.      * Only one client widget can be handled at a time; multiple calls
  111.      * of setView will cause only the last widget to be added to be
  112.      * properly handled.
  113.      *
  114.      * The widget must have been created with this instance of
  115.      * KTMainWindow as its parent.
  116.      */
  117.     void setView( QWidget *view, bool show_frame = TRUE );
  118.  
  119.     
  120.     /**
  121.      *Enable or disable the status bar.
  122.      */
  123.     void enableStatusBar( KStatusBar::BarStatus stat = KStatusBar::Toggle );
  124.  
  125.     /**
  126.      * Enable or disable the toolbar with the ID specified.
  127.      * If no ID is specified, the default ID is 0.
  128.      */
  129.     void enableToolBar( KToolBar::BarStatus stat = KToolBar::Toggle,
  130.                         int ID = 0 );
  131.  
  132.     /**
  133.      * Set the width of the view frame.
  134.      * If you request a frame around your view with setView(...,TRUE),
  135.      * you can use this function to set the border width of the frame.
  136.      * The default is 1 pixel. You should call this function before
  137.      * setView().
  138.      */
  139.     void setFrameBorderWidth( int );
  140.  
  141.     /**
  142.      * Returns a pointer to the toolbar with the specified ID. 
  143.      * If there is no such tool bar yet, it will be generated
  144.      */
  145.     KToolBar *toolBar( int ID = 0 );
  146.  
  147.     /**
  148.      * Returns a pointer to the menu bar. If there is no
  149.      * menu bar yet, it will be generated
  150.      */
  151.     KMenuBar *menuBar();
  152.  
  153.     /**
  154.      * Returns a pointer to the status bar. If there is no
  155.      * status bar yet, it will be generated
  156.      */
  157.     KStatusBar *statusBar();
  158.  
  159.  
  160.     /* you probably do not need this. Anyway, if you are porting code
  161.      * which have been written for the former KTopLevelWidet you may
  162.      * find the following three boolean has-functions useful:
  163.      */
  164.     
  165.     /*returns wether the menubar is existing 
  166.      */
  167.     bool hasMenuBar();
  168.     /*returns wether the statusbar is existing 
  169.      */
  170.     bool hasStatusBar();
  171.     /*returns wether the specified toolbar  is existing 
  172.      */
  173.     bool hasToolBar( int ID = 0);
  174.  
  175.  
  176.  
  177.     /**
  178.      * Shows toplevel widget. Reimplemented from QWidget, and calls
  179.      * @ref #updateRects. Therefore, it is now enough just to show KTMW.  */
  180.     virtual void show ();
  181.  
  182.     /**
  183.      * Distance from top of window to top of main view,
  184.      * Computed in @ref #updateRects. Changing of this variable
  185.      * has no effect. Avoid using it, it might be removed in future.
  186.      */
  187.     int view_top;
  188.  
  189.     /**
  190.      * Distance from top of window to bottom of main view.
  191.      * Computed in @ref #updateRects. Changing of this variable
  192.      * has no effect. Avoid using it, it might be removed in future.
  193.      */
  194.     int view_bottom;
  195.  
  196.     /**
  197.      * Distance from left edge of window to left border of main view.
  198.      * Computed in @ref #updateRects. Changing of this variable
  199.      * has no effect. Avoid using it, it might be removed in future.
  200.      */
  201.     int view_left;
  202.  
  203.     /**
  204.      * Distance from left edge of window to right edge of main view.
  205.      * Computed in @ref #updateRects. Changing of this variable
  206.      * has no effect. Avoid using it, it might be removed in future.
  207.      */
  208.     int view_right;
  209.  
  210.  
  211.  
  212.   /**
  213.    * Try to restore the toplevel widget as defined number (1..X)
  214.    * If the session did not contain that high number, the configuration
  215.    * is not changed and False returned.
  216.    * 
  217.    * That means clients could simply do the following:
  218.    * <pre>
  219.    * if (kapp->isRestored()){
  220.    *   int n = 1;
  221.    *   while (KTMainWindow::canBeRestored(n)){
  222.    *     (new childTLW)->restore(n);
  223.    *     n++;
  224.    *   }
  225.    * } else {
  226.    * // create default application as usual
  227.    * }
  228.    * </pre>
  229.    * Note that "show()" is called implicit in restore.
  230.    *
  231.    * With this you can easily restore all toplevel windows of your
  232.    * application.  
  233.    *
  234.    * If your application uses different kinds of toplevel
  235.    * windows, then you can use KTMainWindow::classNameOfToplevel(n)
  236.    * to determine the exact type before calling the childTLW
  237.    * constructor in the example from above.  
  238.    * 
  239.    * If your client has only one kind of toplevel widgets (which should
  240.    * be pretty usual) then you should use the RESTORE-macro:
  241.    *
  242.    * <pre>
  243.    * if (kapp->isRestored())
  244.    *   RESTORE(childTLW)
  245.    * else {
  246.    * // create default application as usual
  247.    * }
  248.    * </pre>
  249.    *
  250.    * The macro expands to the term above but is easier to use and
  251.    * less code to write.
  252.    *
  253.    *(Matthias) 
  254.    */
  255.   static bool canBeRestored(int number);
  256.  
  257.  
  258.   /** Returns the className of the numberth toplevel window which
  259.     * should be restored. This is only usefull if you application uses
  260.     * different kinds of toplevel windows. (Matthias) 
  261.     */
  262.   static const QString classNameOfToplevel(int number);
  263.  
  264.   /** try to restore the specified number. Returns "False" if this
  265.    * fails, otherwise returns "True" and shows the window
  266.    */
  267.   bool restore(int number);
  268.  
  269.   /**
  270.     * Tells the session manager wether the window contains
  271.     * unsaved data which cannot be stored in temporary files
  272.     * during saveYourself. Note that this is somewhat bad style.
  273.     * A really good KDE application should store everything in
  274.     * temporary recover files. Kapplication has some nifty support
  275.     * for that.
  276.     *
  277.     * Default is False == No unsaved data.
  278.     */
  279.   void setUnsavedData( bool );
  280.  
  281.  
  282. protected:
  283.   /** Default implementation calls @ref #updateRects if main widget
  284.      * is resizable. If mainWidget is not resizable it does
  285.      * nothing. You shouldn't need to override this function.  
  286.      */
  287.     virtual void resizeEvent( QResizeEvent *e);
  288.     /**
  289.      * Default implementation just calls repaint (FALSE);
  290.      */
  291.     virtual void focusInEvent ( QFocusEvent *);
  292.     /**
  293.      * Default implementation just calls repaint (FALSE);
  294.      */
  295.     virtual void focusOutEvent ( QFocusEvent *);
  296.  
  297.     /** 
  298.       * This is called when the widget is closed.
  299.       * The default implementation will also destroy the
  300.       * widget.(Matthias)
  301.       */
  302.     virtual void closeEvent ( QCloseEvent *);
  303.  
  304.   /** KTMainWindow has the nice habbit that it will exit the
  305.     * application when the very last KTMainWindow is
  306.     * destroyed. Some applications may not want this default
  307.     * behaviour,for example if the application wants to ask the user
  308.     * wether he really wants to quit the application.  This can be
  309.     * achived by overloading the queryExit() method.  The default
  310.     * implementation simply returns TRUE, which means that the
  311.     * application will be quitted. FALSE will cancel the exiting
  312.     * process. (Matthias) */
  313.     virtual bool queryExit();
  314.  
  315.   /** Save your instance-specific properties.
  316.    * You MUST NOT change the group of the kconfig object,
  317.    * since KTMW uses one group for each window.
  318.    * Please overload these function in childclasses. 
  319.    *
  320.    * Note that any interaction or X calls are forbidden
  321.    * in these functions!
  322.    *
  323.    * (Matthias) */
  324.   virtual void saveProperties(KConfig*){};
  325.   /**
  326.   * Read your instance-specific properties.
  327.   */
  328.   virtual void readProperties(KConfig*){};
  329.  
  330.  
  331.     
  332. protected slots:
  333.     /**
  334.      * Updates child widget geometry. This function is now virtual
  335.      * This is automatically called when the widget is created,
  336.      * new components are added or the widget is resized, or showed.
  337.      * updateRects handles fixed-size widgets properly.
  338.      *
  339.      * Override it if you intend to manage the children yourself.
  340.      * You normally do not need to do this.
  341.      */
  342.     virtual void updateRects();
  343.  
  344.  private slots:
  345.  /**
  346.    * React on the request of the session manager (Matthias)
  347.    */
  348.     void saveYourself(); 
  349.  
  350.  
  351.  
  352. private:
  353.  
  354.   /** 
  355.    * List of members of KTMainWindow class
  356.    */
  357.   static QList<KTMainWindow>* memberList;
  358.  
  359.     /**
  360.      * List of toolbars.
  361.      */
  362.     QList <KToolBar> toolbars;
  363.  
  364.     /**
  365.      * Main widget. If you want fixed-widget just call setFixedSize(w.h)
  366.      * on your mainwidget.
  367.      * You should not setFixedSize on KTMainWindow..
  368.      */
  369.     QWidget *kmainwidget;
  370.  
  371.     /**
  372.      * Menubar.
  373.      */
  374.     KMenuBar *kmenubar;
  375.  
  376.     /**
  377.      * Statusbar
  378.      */
  379.     KStatusBar *kstatusbar;
  380.  
  381.     /**
  382.      * Frame around main widget
  383.      */
  384.     QFrame *kmainwidgetframe;
  385.  
  386.     /**
  387.      * Stores the width of the view frame
  388.      */
  389.     int borderwidth;
  390.  
  391.  
  392.   // Matthias
  393. protected:
  394.   void savePropertiesInternal (KConfig*, int);
  395.   bool readPropertiesInternal (KConfig*, int);
  396. };
  397.  
  398.  
  399. #define RESTORE(type) { int n = 1;\
  400.     while (KTMainWindow::canBeRestored(n)){\
  401.       (new type)->restore(n);\
  402.       n++;}}
  403.  
  404. #endif
  405.